textlintの導入方法や使い方を確認してみた
CX事業本部Delivery部のアベシです。
こちらの記事では自然言語用リンターのtextlintの導入方法やルールの適応方法に調べてみましたので紹介します。
また、huskyと連携させてコミット前にチェックさせる方法も試しましたので併せて紹介したいと思います。
はじめに
ドキュメントを用意する場合、書いた後に文章の体裁やタイポの添削をご自分でされると思うのですが、私の場合どうしても抜け漏れが発生してしまうのが最近の悩みでした。
結果として体裁の整っていない文章をPRに出してしまったり、ブログに投稿してしまったり、やらかしてました。
こういった事を防ぎたいと思って相談したところ先輩に紹介してもらったのがtextlintです。
textlintはインストールしたルールに従って文章をチェックしてくれます。
こちらのリポジトリにも有るルールをそれぞれnpmインストールして追加できます。
デフォルトではMarkdownとtextファイルのチェックが可能です。
公式ページはこちら⇣
AWSサービス名のタイポ
冒頭で述べたやらかしの他にAWSのサービスのタイポも良くやってしまうことの一つでした。
弊社のブログのような外部公開する媒体では特に気をつけなきゃと思って探したところ、弊社の有志が専用のチェックルールtextlint-rule-aws-service-nameを作ってくれてました。
下のリンク先のブログで紹介しています。
今回はこちらも導入してAWSサービス名のチェックができるようにしてみます。
検証環境
以下の環境で検証しました。
| 項目名 | バージョン |
|---|---|
| mac OS | Ventura 13.2 |
| npm | 9.5.0 |
| textlint | 13.3.1 |
| textlint-rule-aws-service-name | 1.1.2 |
| textlint-rule-preset-ja-technical-writing | 7.0.0 |
textlintの導入
今回どのプロジェクトでも任意で使えるようにしたかったので、textlintをグローバルインストールする形で導入してみました。
textlintのインストール
インストールコマンドは以下です。
$ npm i -g textlint
ルールプリセットのインストール
次にルールのプリセットをインストールします。
今回は技術書向けのルールがまとまっているプリセットのtextlint-rule-preset-ja-technical-writingをインストールします。
インストールコマンドは以下です。
$ npm i -g textlint-rule-preset-ja-technical-writing
ルールの適応方法
インストールしたルールの適応方法は以下の２通りあります。
- textlintコマンドにオプションで使いたいルールを指定する。
- .textlintrc.jsonにルールを記載する。
1.の場合
コマンドにオプションを付けて実行する場合のコマンドは以下となります。
$ textlint --preset <プリセット名> <ファイルのパス> // 使用例 $ textlint --preset ja-technical-writing ./sample-file/sample1.md //結果 2:6 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 5:14 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period
2.の場合
今回は2.の.textlintrc.jsonにルールを記載する方法を使っていきます。
こちらの方法ではプリセットの一部のルールを適応させない、といったカスタマイズが可能です。
設定するには.textlintrc.jsonの作成が必要です。
以下のtextlintコマンドで作成されます。
グローバルインストールの場合は、ホームディレクトリに移動してから実行します。
$ cd ~ $ textlint -init
作成された.textlintrc.jsonを以下のように編集するとインストールしたプリセットtextlint-rule-preset-ja-technical-writingの全てのルールを使ってチェックされます。
{
"plugins": {},
"filters": {},
"rules": {
"preset-ja-technical-writing": true
}
}
リンターの実行
2.の.textlintrc.jsonにルールを書く場合は以下の手順でドキュメントのチェックを実行できます。
こちらではtextlintコマンドの後にファイルのパスのみ付ける事で実行が可能となります。
$ textlint <ファイルのパス> // 使用例 $ textlint ./sample-file/sample1.md //結果 2:6 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 5:14 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period
プロジェクトのディレクト内に複数のドキュメントが有る場合はワイルドカードを使用してディレクトリ内の全てのドキュメントに対してチェックを走らすことができます。
// プロジェクトのルートディレクトで以下のコマンド実行 $ textlint * //結果 textlint * /Users/*********/product_practice/textlint-test/sample-files/sample1.md 2:6 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 5:14 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period /Users/*********/product_practice/textlint-test/sample2.md 2:6 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 5:14 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period ✖ 4 problems (4 errors, 0 warnings)
ルールのカスタマイズ
.textlintrc.jsonファイルのプリセット名の値にルール名のプロパティを記載します。
その値にfalseを指定する事でプリセットに含まれる特定のルールのみ適用させない、ということが可能です。
ここでは先程の実行で該当したja-no-weak-phraseというルールを除外してみます。
{
"plugins": {},
"filters": {},
"rules": {
"preset-ja-technical-writing": {
"ja-no-weak-phrase": false
}
}
}
こちらでもう一度textlintを実行した結果が以下となります。
$ textlint ./sample-file/sample1.md /Users/*********/Documents/blog/write_vs-code/textlint/sample-file/sample1.md 5:14 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period ✖ 1 problem (1 error, 0 warnings)
先程、ルールを除外する前に指摘されたerror 弱い表現: "思います" が使われています。が消えています。
AWSサービス名をチェックするルールを追加
冒頭で紹介したtextlint-rule-aws-service-nameを導入してみたいと思います。
まずは以下のコマンドでグローバルインストールします。
npm i -g textlint-rule-aws-service-name
.textlintrc.jsonに追加します
{
"plugins": {},
"filters": {},
"rules": {
"preset-ja-technical-writing": {
"ja-no-weak-phrase": false
},
"aws-service-name":true
}
}
テスト用に以下のファイルを作りました。正しいサービス名称はStepとFunctionsの間にスペースが入ります。
StepFunctions
結果
$ textlint ./sample-file/wrong-aws-name.md /Users/**********/Documents/blog/write_vs-code/textlint/sample-file/wrong-aws-name.md 1:1 ✓ error StepFunctions => Step Functions aws-service-name ✖ 1 problem (1 error, 0 warnings) ✓ 1 fixable problem. Try to run: $ textlint --fix [file]
1:1 ✓ error StepFunctions => Step Functions aws-service-nameといった感じでちゃんと指摘されました。
✓ 1 fixable problem.という記述があります。これはtextlintコマンドを使って修正可能であることを意味しています。
警告を受けた項目の修正
チェックの結果✓ 1 fixable problem.となった項目は以下のコマンドで修正可能です。
$ textlint --fix <ファイルパス>
先程のAWSの名前を修正してみます。
$ textlint --fix ./sample-file/wrong-aws-name.md
結果
t$ extlint --fix sample-file/wrong-aws-name.md /Users/**********/Documents/blog/write_vs-code/textlint/sample-file/wrong-aws-name.md 1:1 ✔ StepFunctions => Step Functions aws-service-name ✔ Fixed 1 problem
ファイル内の名称が自動的に修正されました 。
Step Functions
huskyと組み合わせる
huskyを使うとコミットをトリガーにして指定したコマンドを走らすことができます。
コマンドが失敗する場合はコミットが失敗するようになります。
この機能を利用してコミットのタイミングでtextlintを実行して、チェックにひっかかったらコミットを失敗させるようにしてみました。
huskyについては下のブログで紹介しましたので、参考にしていただければと思います。
以下のコマンドでプロジェクトにhuskyを導入します。
$ npx husky-init && npm install
作成された.husky/pre-commitにtextlintの実行コマンドを記載します。
.husky/pre-commit #!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" textlint * // ここにtextlintの実行コマンドを追加します。
対象のmarkdownファイルを修正してコミットすると、以下のエラーが出て期待通りコミットが失敗してくれました。
以上
